/*
 * Copyright 2009 Armando Blancas
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package taskgraph.ports;

import java.io.EOFException;
import java.io.IOException;

/**
 * An input interface to a Short Channel.
 * 
 * @author Armando Blancas
 */
public interface ShortInputPort extends Port {
	
    /**
     * Reads and returns the next {@code short} integer value. 
     *
     * @return The {@code short} value read.
     * @throws EOFException If the channel reaches the end.
     * @throws IOException If an I/O error occurs.
     */
    short read() throws IOException;

    /**
     * Reads into an array of short integers.
     * 
     * Reads a number of short integers from this input pipe and stores them 
     * into the {@code short} array {@code s}. The number of shorts actually 
     * read is returned as an {@code int}. This method blocks until input data
     * is available, end of file is detected, or an exception is thrown.
     *
     * <p>If the length of {@code s} is zero, then no shorts are read and
     * {@code 0} is returned; otherwise, there is an attempt to read at
     * least one {@code short}. If no short is available because the output
     * end is closed, an {@code IOException} is thrown; otherwise, at least
     * one short is read and stored into {@code s}.
     *
     * <p>The first short read is stored into element {@code s[0]}, the
     * next one into {@code s[1]}, and so on. The number of shorts read is,
     * at most, equal to the length of {@code s}. Let <i>k</i> be the
     * number of shorts actually read; these shorts will be stored in 
     * elements {@code s[0]} through {@code s[k-1]}, leaving elements 
     * {@code s[k]} through {@code s[s.length-1]} unaffected.
     * 
     * <p>The general contract for {@code read(s)} is that it should have 
     * exactly the same effect as the call {@code read(s, 0, s.length)}.
     *
     * @param s The {@code short} array into which the data is read.
     * @return The total number of shorts read into the array.
     * @throws IOException If the first short cannot be read, the output end
     *         has been closed, or if some other I/O error occurs.
     * @throws NullPointerException If {@code s} is {@code null}.
     */
    int read(short[] s) throws IOException;

    /**
     * Reads into an array of short integers.
     * 
     * Reads up to {@code len} short integers from this input pipe into an 
     * array of {@code short}. Less than {@code len} shorts will be read if 
     * the output end of the data pipe is closed or if {@code len} exceeds 
     * the pipe's buffer size. If {@code len} is zero, then no shorts are 
     * read and 0 is returned; otherwise, the method blocks until at least 
     * 1 {@code short} of input is available, the output end is closed, or 
     * an exception is thrown.
     *
     * @param s    The {@code short} array into which the data is read.
     * @param off  The start offset in the destination array {@code s}.
     * @param len  The maximum number of shorts to read.
     * @return     The total number of shorts read into the array.
     * @throws NullPointerException If {@code s} is {@code null}.
     * @throws IndexOutOfBoundsException If {@code off} is negative, 
     *         {@code len} is negative, or {@code len} is greater than 
     *         {@code s.length - off}.
     * @throws IOException If the pipe is {@code broken},
     *		   closed, or if an I/O error occurs.
     */
    int read(short[] s, int off, int len) throws IOException;

    /**
     * Discards a number of short integers from the buffer.
     * 
     * Makes an attempt to skip over <code>n</code> short integers of data 
     * from the channel, discarding the skipped ones. However, it may skip 
     * over some smaller number of shorts, possibly zero. This may result 
     * from any of a number of conditions; reaching end of channel before 
     * {@code n} shorts have been skipped is only one possibility. This method
     * never throws an <code>EOFException</code>. 
     * The actual number of shorts skipped is returned.
     *
     * @param n The number of short integers to be skipped.
     * @return The number of shorts actually skipped.
     * @throws IOException If an I/O error occurs.
     */
    int skipShorts(int n) throws IOException;

}
